Dial controls must be of type "Dial Control", and have solid bodies. The purpose of "dials" is to support the selection of numbers via the mouse, and/or to graphically display the magnitude of a variable (such as the progress of a calculation).
Operation
The body, frame, indentation, etc., settings are used in the expected way by BaseCt when displaying dials. The content of a dial, however, indicates the current control Value relative to the control's Min and Max. The default appearance of dials is to show the Value as a solid bar drawn in the current content color, filling a fraction of the content area equal to (Value - Min)/(Max - Min). The default behavior of dials is to automatically resize the bar as the user clicks and drags within the content area of the dial.
Options
The following bit values can be added to VarCode to set various dial control options:
1 = disable auto-tracking. Set this option when the dial is being used for display purposes only.
2 = round dial. Forces the content to be drawn using painted arcs instead of rectangles. Auto-tracking is also done in a circular fashion.
4 = fill current value only. Causes just the fraction of the dial's content corresponding to the current Value to be filled (rather than Value - Min). The visual effect is to create a rectangle or wedge that acts like the box or thumb seen in standard scroll bars. NOTE: When this option is set, the displayed Values are Min + 1 to Max, and the user cannot set Value equal to Min (i.e. box or wedge is always displayed). Thus, for example, a dial with Min = 0 & Max = 10 would display 10 Values (1 to 10) corresponding to 10 distinct box or wedge positions.
8 = draw extra frame around content, or, if dial is round, draw vertical line to denote Min value. (Note that if the frame and content are same color, then you won't be able to see the extra frame being drawn.)
16 = auto-update linked variable as dial's Value is changed by user (GetVal is called by BaseCt), and update the state of all other controls in the same view that are linked to the same program variable (BaseCt calls SetVal). This makes it easy, for example, to associate a dial with a text item that is then updated as the dial is adjusted (i.e., link both controls to same variable and add 16 to dial's VarCode). WARNING: If you link multiple controls to the same variable, and then use GetVal to get the values of all controls in the window, then the highest numbered control that is linked to the variable will be the one whose value is seen by the program. If a dial is associated with an editable text item, for example, then the editable item should be placed after the dial in the control list so that the value in the editable item is read, OR GetVal should be called in way that only returns the value of the editable item (since the user can type a value in the editable item that is different from the dial's).
Content Pattern
A "PAT "-type resource can be linked to the dial to force BaseCt to draw the dial's content (= bar, box, wedge, or filled arc) with a pattern. This will have no effect if a separate thumb control is being used to indicate the dial's current value (described below).
Thumb Controls
You can optionally use any static BaseCt control as the dial's thumb. This static control must (1) be the next control in the window after the dial control, (2) have 256 added to its VarCode to denote that it is to be used as a thumb, and (3) have a solid body (or be linked to a resource type that completely fills the control's content area when redrawn).
The default position of the thumb control is to be centered above the dial's current value (see the "Dial + Thumb" example control). If 512 is added to VarCode, the thumb is displayed above horizontal dials, to the left of vertical dials, or outside of round dials. If 1024 is added to VarCode, the thumb is displayed below horizontal dials (see "Dial + cicns" example control), to the right of vertical dials, or inside the content area of round dials.
The exact position of the thumb is also affected by the dial's "fill current value only" option (VarCode 4). If this option is set, then the thumb is centered above and replaces the box or wedge that would be seen without the thumb control. If not set, then the thumb is centered above the end of the bar or arc that would otherwise be drawn as the content of the dial. In the latter case, the thumb replaces drawing of the bar or arc if the thumb is within the dial, but not if it is outside the dial.
Dials that have a separate thumb control can be linked to PICT, ICON, or cicn resources (see "Dial + cicns" example control). In this case, a bar, box, wedge, or arc is never drawn within the control, and only the thumb control can be used to show the dial's current value. VarCode options 32 and 64 are supported for the static PICT, ICON, or cicn being displayed (as described in "Icons, Picts, ..." topic), but the dial's title is never drawn.
Finally, note that the dial associated with a thumb control need not be visible for the thumb to function properly. This might be useful in cases where you need a thumb-like control to operate above a complex drawing (i.e., place the hidden dial above the drawing, and the thumb control above the dial).
Data Linking
Data linking is based on the standard control Value. Use SetVal (with linked dials) or SetCtlValue (any dial) to change a dial's appearance by resetting its current control Value.
The title of a dial control can be optionally used to set an intercept "a" and slope "b" that is to be used when interconverting variables and values, where,
program variable = a + (b)(control value)
The intercept and slope specified in the title should be separated by a single comma (e.g., "-20,1.23"), and can be any real or integer number that can be stored as a 10-byte real. If the dial's title is empty, then BaseCt uses intercept = 0 and slope = 1 (i.e., control value and program variable are the same).
The intercept and slope specified by a dial's title can be changed at any time by using SetCTitle to reset the control's title. The dial's Min and Max define the "precision" of the dial (the total number of distinct values that a user can select), and can also be changed at any time by using SetCtlMin or SetCtlMax.
NOTE: More complex links between dial controls and variables can be implemented by simply overriding the dial's "getCntl" (GetVal) and "setCntl" (SetVal) control messages with a main program procedure that does the conversion of value <-> variable.
